.\"-
.\" Copyright (c) 2000 Poul Henning Kamp and Dag-Erling Smørgrav
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/share/man/man9/vsb.9,v 1.25 2005/12/23 11:49:52 phk Exp $
.\"
.\" XXX
.ds str-Lb-libvarnish Varnish Library (libvarnish, \-lvarnish)
.\" XXX
.Dd March 14, 2006
.Dt VSB 3
.Os
.Sh NAME
.Nm vsb_new ,
.Nm vsb_clear ,
.Nm vsb_bcat ,
.Nm vsb_cat ,
.Nm vsb_printf ,
.Nm vsb_vprintf ,
.Nm vsb_putc ,
.Nm vsb_finish ,
.Nm vsb_data ,
.Nm vsb_len ,
.Nm vsb_delete
.Nd safe string formatting
.Sh LIBRARY
.Lb libvarnish
.Sh SYNOPSIS
.In vsb.h
.Ft struct vsb *
.Fn vsb_new "struct vsb *s" "char *buf" "int length" "int flags"
.Ft void
.Fn vsb_clear "struct vsb *s"
.Ft int
.Fn vsb_bcat "struct vsb *s" "const void *buf" "size_t len"
.Ft int
.Fn vsb_cat "struct vsb *s" "const char *str"
.Ft int
.Fn vsb_printf "struct vsb *s" "const char *fmt" "..."
.Ft int
.Fn vsb_vprintf "struct vsb *s" "const char *fmt" "va_list ap"
.Ft int
.Fn vsb_putc "struct vsb *s" "int c"
.Ft void
.Fn vsb_finish "struct vsb *s"
.Ft char *
.Fn vsb_data "struct vsb *s"
.Ft int
.Fn vsb_len "struct vsb *s"
.Ft void
.Fn vsb_delete "struct vsb *s"
.Sh DESCRIPTION
The
.Nm vsb
family of functions allows one to safely allocate, construct and
release bounded null-terminated strings in kernel space.
Instead of arrays of characters, these functions operate on structures
called
.Fa vsbs ,
defined in
.In sys/vsb.h .
.Pp
The
.Fn vsb_new
function initializes the
.Fa vsb
pointed to by its first argument.
If that pointer is
.Dv NULL ,
.Fn vsb_new
allocates a
.Vt struct vsb
using
.Xr malloc 9 .
The
.Fa buf
argument is a pointer to a buffer in which to store the actual string;
if it is
.Dv NULL ,
.Fn vsb_new
will allocate one using
.Xr malloc 9 .
The
.Fa length
is the initial size of the storage buffer.
The fourth argument,
.Fa flags ,
may be comprised of the following flags:
.Bl -tag -width ".Dv VSB_AUTOEXTEND"
.It Dv VSB_FIXEDLEN
The storage buffer is fixed at its initial size.
Attempting to extend the vsb beyond this size results in an overflow condition.
.It Dv VSB_AUTOEXTEND
This indicates that the storage buffer may be extended as necessary, so long
as resources allow, to hold additional data.
.El
.Pp
Note that if
.Fa buf
is not
.Dv NULL ,
it must point to an array of at least
.Fa length
characters.
The result of accessing that array directly while it is in use by the
vsb is undefined.
.Pp
The
.Fn vsb_delete
function clears the
.Fa vsb
and frees any memory allocated for it.
There must be a call to
.Fn vsb_delete
for every call to
.Fn vsb_new .
Any attempt to access the vsb after it has been deleted will fail.
.Pp
The
.Fn vsb_clear
function invalidates the contents of the
.Fa vsb
and resets its position to zero.
.Pp
The
.Fn vsb_bcat
function appends the first
.Fa len
bytes from the buffer
.Fa buf
to the
.Fa vsb .
.Pp
The
.Fn vsb_cat
function appends the NUL-terminated string
.Fa str
to the
.Fa vsb
at the current position.
.Pp
The
.Fn vsb_printf
function formats its arguments according to the format string pointed
to by
.Fa fmt
and appends the resulting string to the
.Fa vsb
at the current position.
.Pp
The
.Fn vsb_vprintf
function behaves the same as
.Fn vsb_printf
except that the arguments are obtained from the variable-length argument list
.Fa ap .
.Pp
The
.Fn vsb_putc
function appends the character
.Fa c
to the
.Fa vsb
at the current position.
.Pp
The
.Fn vsb_finish
function null-terminates the
.Fa vsb
and marks it as finished, which means that it may no longer be
modified using
.Fn vsb_cat ,
.Fn vsb_printf
or
.Fn vsb_putc .
.Pp
The
.Fn vsb_data
and
.Fn vsb_len
functions return the actual string and its length, respectively;
.Fn vsb_data
only works on a finished
.Fa vsb .
.Sh NOTES
If an operation caused an
.Fa vsb
to overflow, most subsequent operations on it will fail until the
.Fa vsb
is finished using
.Fn vsb_finish
or reset using
.Fn vsb_clear .
.Sh RETURN VALUES
.Fn vsb_new
returns
.Dv NULL
if it failed to allocate a storage buffer, and a pointer to the new
.Fa vsb
otherwise.
.Pp
.Fn vsb_cat ,
.Fn vsb_printf ,
and
.Fn vsb_putc
all return \-1 if the buffer overflowed, and zero otherwise.
.Pp
.Fn vsb_data
and
.Fn vsb_len
return
.Dv NULL
and \-1, respectively, if the buffer overflowed.
.Sh SEE ALSO
.Xr printf 3 ,
.Xr strcat 3 ,
.Xr strcpy 3
.Sh HISTORY
The
.Nm vsb
family of functions first appeared in
.Fx 4.4 .
.Sh AUTHORS
.An -nosplit
The
.Nm vsb
family of functions was designed by
.An Poul-Henning Kamp Aq phk@FreeBSD.org
and implemented by
.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
Additional improvements were suggested by
.An Justin T. Gibbs Aq gibbs@FreeBSD.org .
Auto-extend support added by
.An Kelly Yancey Aq kbyanc@FreeBSD.org .
.Pp
This manual page was written by
.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
